The term "combing" is used as a general term versus "interlacing" because interlacing is usually associated with nonprogressive streams. What look like interlacing artifacts can be seen on telecined progressive streams, so I use the term combing to refer to all such artifacts, regardless of the type of the stream.
The package automatically adapts to any telecine/capture patterns, and mixtures thereof, although if you want to decimate the recovered progressive stream, you have to specify the desired decimation ratio if it differs from the default 1-in-5 used for 3:2 NTSC. None of the functions introduce a delay in the audio or video streams.
For many applications, there are no parameters to set. Some capture cards require a field swap after the recovery process and the Telecide function allows this to be specified.
All of Decomb's decisions can be manually overriden as desired using text override files. This allows meticulous users to achieve the best possible quality for their encodes.
The package consists of the following functions:
By default, Telecide runs postprocessing on the recovered frames. This postprocessing checks each frame to see if it is combed (some combed frames may come through the field-matching process [see below]), and if a frame is combed, it is deinterlaced, otherwise it is not touched. The deinterlacing algorithm is a space-adaptive one, that is, only the portions of a frame that are combed are deinterlaced. This means that full detail is retained in static picture areas. The algorithm for distinguishing between combed and progressive frames is effective but not perfect.
To achieve inverse telecine, apply Telecide followed by Decimate.
Telecide supports an optional pattern guidance mode. Enabling this option allows Telecide to overrule the calculated field match with its predicted match based on the recent clip history. A threshold can be defined so that a large enough discrepancy between the predicted and calculated matches will reset the pattern.
FieldDeinterlace provides an option that allows you to specify whether all frames are to be deinterlaced or whether just frames detected to be combed are deinterlaced.
Do not resize vertically before applying Decomb. Decomb needs to see the original line spacing to properly detect combing.
Telecide requires YUY2 color format as input. If you require YV12 for working natively with DVD content, you must use a recent version Avisynth 2.5 in conjunction with DecombYV12. The DLL shipped with this version of Decomb will work only with legacy Avisynth versions (2.0x).
Don't Postprocess Unnecessarily Try Telecide without postprocessing if you think there is a chance that you have a nice clean input stream. If you do have such a stream, you'll find that processing runs much faster without postprocessing. If you encounter combed first and/or last frames only with postprocessing off, then set the firstlast flag to true.
Don't Invoke an Avisynth Strangeness This one is very important and can easily cost you a 25% speed penalty! It appears that Avisynth has a strangeness that causes it to waste enormous amounts of time when there are no parentheses with the commands. For example, this script:
Telecide
Decimate
…will run much slower than this one:
Telecide()
Decimate()
If you doubt this, try it both ways and see. It is critical, therefore, to always include at least one parameter or the set of empty parentheses. That is why the scenarios below all are coded that way.
Use Fast Recompress If Possible If you are serving into VirtualDub for transcoding, and you don't need to do any filtering or other processing in VirtualDub, then use VirtualDub's Fast Recompress mode.
Disable Frame Displays When sending Decomb output to VirtualDub (and similar applications), disable the display of the input and output frames during processing. This will noticeably decrease processing time.
Interpolation Can be Faster than Blending If your clip requires a lot of frames to be deinterlaced, you'll find that processing is a little faster if you use blend=false.
LoadPlugin("decomb.dll")
AVISource("nonfilm.avi")
FieldDeinterlace()
Progressive Frame Recovery If you have telecined film (progressive) source and want to recover the progressive frames but not change the frame rate by decimating, you proceed as follows:
LoadPlugin("decomb.dll")
AVISource("film.avi")
Telecide()
Note that here Telecide does postprocessing of the recovered frames to clean up any combed frames that might have come through the field-matching process (see "Notes on Field Matching" below).
If you are curious to know what decisions Telecide is making about which frames are combed, you can use the show option, or the debug option in conjunction with the DebugView utility, to assess this and possibly tweak Telecide's threshold (see "Decomb Function Syntax" below).
Inverse Telecine (IVTC) If you want to do the same thing but decimate the result to remove duplicated frames (which amounts to performing an inverse telecine [IVTC] operation), you proceed as follows [NTSC 3:2 uses Decimate(cycle=5)]:
LoadPlugin("decomb.dll")
AVISource("film.avi")
Telecide()
Decimate(cycle=5)
Disabling Postprocessing If your telecined source material is very clean, you may want to disable postprocessing to reduce processing time. Proceed as follows:
LoadPlugin("decomb.dll")
AVISource("mixed.avi")
Telecide(post=false)
Decimate(cycle=5)
Here the third parameter, post, is set to false to disable postprocessing.
Inverse 3:2 Telecine with Pattern Guidance If your telecined source material is NTSC 3:2 pulldown, you can enable pattern guidance, which can make the field matching more accurate for some clips. Proceed as follows:
LoadPlugin("decomb.dll")
AVISource("mixed.avi")
Telecide(guide=1)
Decimate(cycle=5)
Refer to the syntax description for Telecide() below for more details.
Forcing Matching Reversal Some DVDs have been seen to output some out-of-order bottom fields, causing IVTC failure. This (and other similar situations) can sometimes be corrected by forcing Telecide to reverse the sense of its field matching (instead of matching on the second field, match on the first field). This is worth a try if you find that a lot of seriously interlaced frames are coming through Telecide. It may also be useful when there are a preponderance of blended fields limited to the second field.
LoadPlugin("decomb.dll")
AVISource("mixed.avi")
Telecide(reverse=true)
Processing Hybrid Clips Some clips mix film and nonfilm content. One way to handle these is to leave them at the original frame rate and let Decimate determine what to do with the frames that would otherwise have been dropped:
LoadPlugin("decomb.dll")
AVISource("hybrid.avi")
Telecide()
Decimate(mode=1)
Refer to the following section and the syntax description for the threshold parameter for an explanation of the processing that will occur with this script.
Sometimes you'll encounter clips where the blended fields are predominantly in the second field. In such cases reversing the sense of Telecide's matching as described above may improve things. This reversal is always worth trying when you encounter a lot of blended fields.
I have seen streams that have blended fields in almost every frame and not limited to the first field. If this is the case, there is no point in using Telecide at all. Just use FieldDeinterlace (full=true) to treat the video as totally interlaced.
Finally, how do you tell if your stream has blended fields? Simply use the Avisynth SeparateFields function to split the fields apart and then serve the result to VirtualDub. Step through the fields and see if there are any fields that are blends of more than one picture.
Telecide(post=false,debug=true)
Any combination and order of named parameters is allowed. Remember, however, that you should always include empty parentheses if you are not specifying any parameters.
REGEDIT4
[HKEY_LOCAL_MACHINE\SOFTWARE\Avisynth]
"PluginDir"="d:\\avisynthplugins"
Next, create defaults files as required in the plugins directory. For example, to set the default post=false for Telecide(), make a file called Telecide.def and put this line in it:
post=false
You can list as many parameter assignments as you like, one per line. Those not specified assume the values given below. Of course, you can always override the defaults in your scripts when you invoke the functions. NOTE: The lines in the defaults file must not contain any spaces or tabs.
Overriding Telecide() For example, suppose we find that frame 100 is not being field-matched correctly. We inspect Telecide()'s debug output and find that it is matching to the previous frame ("[using p]"). We want to try forcing a match to current and next to see if a correct match can be found (refer to APPENDIX A for an explanation of the terminology). First we make a file in the same directory as the script file called "tango.tel" (you can use any filename). Then we place this line in the file:
100 c
This declares that frame 100 is to be matched to current (use "p" for previous frame and "n" for next).
Now we direct Telecide to use this overrides file:
Telecide(ovr="tango.tel")
Now process the script as usual; the specified override to current will be used. If this match fails we can try replacing "c" with "n" to try next.
A frame range can also be used, such as:
100,500 c
We can add additional lines defining any other overrides as required. Note that the frame numbers must be in ascending order (from lowest to highest).
You can also specify full patterns for your matching in the Telecide overrides file. For example, suppose you wanted to force a pattern of ncccn for frames 100 through 185. Your overrides file line would be:
100,185 ncccn
You can put as many specifiers in the pattern as you like. For example, this would be legal too:
100,185 nc
The specified pattern will be repeated beginning at the starting frame and ending at the ending frame of the range.
This capability allows for flexible and convenient manual control of field matching. You can do your whole film manually if you like!
Telecide()'s postprocessing decisions can also be overridden. To force a frame to be considered combed, use a line with a '+' like these:
100 +
100,500 +
To force a frame to be considered NOT combed, use lines like this:
100 -
100,500 -
Lines for overriding field matching and for overriding postprocessing can be used together in the same overrides file as long as the ascending frame number requirement is met.
Overriding FieldDeinterlace() Forcing overrides for FieldDeinterlace() works exactly as described for Telecide(). Of course, field matching overrides do not apply and should not be used. You might want to call the overrides file "tango.fd".
Overriding Decimate() For Decimate(), we do things the same way but we use lines of the following form, where the numbers are frame numbers of the clip entering Decimate() that will be forced to be decimated:
150
175
In the above example, frames 150 and 175 will be force decimated. Again, an appropriate name for the overrides file would be "tango.dec".
Telecide(parameter_list)
Commonly used parameters
guide (0-3, default 0) can be used to greatly improve field matching when the source clip is known to be PAL or NTSC telecined material. To disable this option (blind field matching), set guide=0. For NTSC 24fps->30fps telecine guidance, set guide=1. For simple PAL guidance (tries to maintain lock to the field phase), set guide=2. For NTSC 25fps->30fps telecine guidance, set guide=3.
When this option is enabled, Telecide() can overrule a field match decision and use a predicted match based on the recent clip history. The gthresh parameter (below) is used to define how large a discrepancy between the predicted and calculated field matches is required to reset the pattern. Do not enable this option unless you know that the source clip corresponds to the selected guidance mode. If in doubt, leave guide=0.
Note that this feature buffers the calculations from the 5 frames (NTSC) or 3 frames (PAL) preceding the current frame. Because of this, pattern guidance will not be effective during random frame access (e.g., while jumping around on the VirtualDub timeline). To get the benefit of this feature, play the clip straight through from a starting point; do not use random access). Of course, this is how things are done when encoding, so this limitation is irrelevant during normal operation.
gthresh (0-100, default 30) defines how large a discrepancy between the predicted and calculated field matches is required to reset the pattern. Use the debug option, if required, to appropriately tweak this threshold. The debug output will indicate which matches have been overridden.
post (true/false, default true) controls whether Telecide performs postprocessing to clean up frames that come through the field-matching still combed. Use true to enable postprocessing.
threshold (0-255, default 15) sets the combed frame detection threshold for the postprocessing. You may want to increase this value if too many good frames are being deinterlaced, or reduce it if small combed areas are not getting caught. The default is a good general purpose value. Note that this threshold determines whether a frame is considered combed and needs to be deinterlaced; it is not the threshold you might be familiar with in Smart Deinterlacer. That threshold is determined by dthreshold (below); it is the threshold for deinterlacing the frames detected as combed.
dthreshold (0-255, default 9) sets the threshold for deinterlacing frames detected as combed. Note that this threshold is the threshold you might be familiar with in Smart Deinterlacer.
blend (true/false, default true) enables blending instead of interpolating in combed areas.
show (true/false, default false) enables metrics to be displayed on the frame to assist with tweaking of thresholds. Also displays the software version.
agg (true/false, default false) forces aggressive pattern guidance.
reverse (true/false, default false) is used to reverse the sense of Telecide's field matching, i.e., instead of matching on the second field, match on the first field.
swap (true/false, default false) is required if the result of Telecide comes out field-swapped; some capture cards require it.
firstlast (true/false, default false) can be used to force the first and last frames to be deinterlaced. This can be required when a field is missing at the beginning or end of the clip (PAL phase shift often causes this). Set this option to true to force deinterlacing of the first and last frames.
chroma (true/false, default false) includes chrominance in the deinterlace calculations. When deciding which areas are interlaced, the chrominance bytes are tested as well as the luminance bytes. It is possible for pixels to have different colors while being very close in luminance, resulting in a failure to detect combing. This usually happens more often with animations. Setting the chroma option to true solves this problem at the expense of processing speed. Note that this option is equivalent to the "compare color channels" option in Smart Deinterlacer.
nt (integer, default 0) defines the noise rejection threshold. It should not be necessary to adjust this parameter and it is not recommended. For really clean clips, you might usefully lower nt.
mm (integer, default 0) defines the matching mode. Set mm=0 (default) for the current matching behavior, i.e., tries to match to current/previous/next. Set mm=1 to match only to current/previous. Set mm=2 to match only to current/next. These modes are useful when you know the clip's parity (top or bottom first), because you can both run faster and prevent some spurious matches. This should be used only by experts who know when it can be safely used.
y0 and y1 (integer, default 0) define an exclusion band for the field matching. If y0 is not equal to y1 this feature is enabled. Rows in the image between lines y0 and y1 (inclusive) are excluded from consideration when the field matching is decided. This feature is typically used to ignore subtitling, which might otherwise throw off the matching. y0 and y1 must both be positive integers and y0 must be less than or equal to y1; if this is violated an exception will be thrown.
ovr (string, default "") enables specification of an overrides file (see the section above called "Overriding Decomb Decisions"). The file must be in the same directory as the script file (the Avisynth current directory) and the filename must be enclosed in quotation marks, e.g., ovr="tango.tel".
debug (true/false, default false) enables logging/debugging information about the filter's decisions to be printed via OutputDebugString(). A utility called DebugView is available for catching these strings.
FieldDeinterlace(parameter_list)
full (true/false, default true) chooses whether to process all frames or just the frames that are detected as combed. Use full=true to process all frames.
threshold (0-255, default 15) sets the combed frame detection threshold. When running with full=false, you may want to increase this value if too many good frames are being deinterlaced, or reduce it if small combed areas are not getting caught. The default is a good general purpose value. Note that this threshold determines whether a frame is considered combed and needs to be deinterlaced; it is not the threshold you might be familiar with in Smart Deinterlacer. That threshold is determined by dthreshold (below); it is the threshold for deinterlacing the frames detected as combed. When full=true, threshold is ignored, but dthreshold remains functional.
dthreshold (0-255, default 9) sets the threshold for deinterlacing frames detected as combed. Note that this threshold is the threshold you might be familiar with in Smart Deinterlacer.
blend (true/false, default true) enables blending instead of interpolating in combed areas.
chroma (true/false, default false) is the same as described for Telecide.
ovr (string, default "") enables specification of an overrides file (see the section above called "Overriding Decomb Decisions"). The file must be in the same directory as the script file (the Avisynth current directory) and the filename must be enclosed in quotation marks, e.g., ovr="tango.fd".
show (true/false, default false) enables metrics to be displayed on the frame to assist with tweaking of thresholds. Also displays the software version.
debug is the same as described for Telecide.
cycle (2-25, default 5) selects the decimation ratio, that is, decimate 1 frame in every cycle frames.
mode (0-2, default 0) determines how Decimate() deals with the extra frame in the cycle.
If mode=0, Decimate discards the frame in the cycle determined to be most similar to its predecessor.
If mode=1, instead of discarding the most similar frame, Decimate() will either replace it with a frame interpolated between the current frame (usually a duplicate of the preceding frame) and the following frame, or it will pass the frame through as is. The choice between these two depends on the threshold parameter setting and on how different the frame is from its preceding frame (see below). Decimate(mode=1) is useful for hybrid clips where you do not want to reduce the frame rate but want to ameliorate the effect of duplicate frames that are emitted by Telecide() (frames that are normally removed with mode=0).
If mode=2, Decimate() deletes a frame from the longest run of duplicates. This mode is the most reliable with anime and other material where the motion may occur only in every second, third, or fourth (etc.) frames. If you use mode=0 on such clips, there is a danger that incorrect decimation may occur, causing jerkiness. Clips such as those described usually derive from 8fps or 12fps animation, as well as normal 24fps animation where slow motion results in repeated duplicates. Mode=2 is able to delete the correct duplicates in all these cases.
threshold (decimal, default 0.0) When mode=1, frames determined to be the most similar to their preceding frame can be treated in two possible ways: 1) they can be blended as described above, or 2) they can be passed through if the threshold parameter is non-zero and the difference metric exceeds the threshold. By setting an appropriate threshold, you can have duplicates get blended while passing through frames that have new content, i.e., which differ significantly from the previous frame. This allows hybrid film/nonfilm clips to be dealt with intelligently: the film portions will have blends and the nonfilm portions will not. The threshold parameter has no effect when mode=0. Use show=true (or debug=true in conjunction with the DebugView utility) to view the difference metrics and thereby determine an appropriate threshold for your clip.
threshold2 (decimal, default 3.0) When mode=2, Decimate() deletes a frame from the longest run of duplicates as described above. The threshold2 parameter controls how close two frames must be to be considered duplicates. If threshold2 is raised, a larger frame difference is tolerated while still declaring them as duplicates. The default setting works well for most clips. Use show=true (or debug=true in conjunction with the DebugView utility) to view the difference metrics and thereby determine an appropriate threshold for your clip.
quality (0-3, default 2) This option allows the user to trade off quality of difference detection against speed. Following are the possibilities:
ovr (string, default "") enables specification of an overrides file (see the section above called "Overriding Decomb Decisions"). The file must be in the same directory as the script file (the Avisynth current directory) and the filename must be enclosed in quotation marks, e.g., ovr="tango.dec".
show (true/false, default false) enables metrics to be displayed on the frame to assist with tweaking of thresholds. Also displays the software version.
debug (true/false, default false) enables logging/debugging information about the filter's decisions to be printed via OutputDebugString(). A utility called DebugView is available for catching these strings. The information displayed is the same as shown by the show option above.
Pt Ct Nt
Pb Cb Nb
Telecide makes 3 combinations of frames from the available fields (this is the big difference from GreedyHMA, which makes only 2 and is therefore sensitive to field dominance — this should become clear as the explanation proceeds). Here are the combinations:
Pt
Cb
Ct
Cb
Nt
Cb
Now each of these frames is checked for combing. The least combed frame is the output frame (assuming no pattern guidance). It is that simple.
Now let's consider a 3:2 pulldown (telecined) sequence:
At Bt Bt Ct Dt
Ab Bb Cb Db Db
Consider the matching of the third frame. Telecide matches Cb from the current frame with Ct of the next frame.
Now consider the same sequence with reversed field dominance:
Ab Bb Cb Db Db
At Bt Bt Ct Dt
Now Telecide matches Bt from the current frame with Bb from the previous frame. So, to be immune to field dominance, it is clear that both the previous and following frames must be checked.
The reverse option to Telecide just makes him reverse which field in the current frame is used to make the 3 combinations. So the 3 frames checked would be:
Ct
Pb
Ct
Cb
Ct
Nb
It doesn't much matter which way you set the reverse option because Telecide will find the progressive frames either way. When it does matter, however, is when you have some problem fields limited to one or the other of top or bottom. The classic example is blended fields. You may be able to find good matches without blends if the blends are in just the top or bottom fields. Beyond that the reverse option doesn't have much use. It doesn't reverse the field dominance of the output stream, for instance.
I'd also like to thank Darryl Andrews for his valuable assistance in specifying and testing the new features in Version 4.00.
Members of the forum at doom9.org provided much help and encouragment.
Copyright © 2002, Donald A. Graft, All Rights Reserved.
Feedback/inquiries to neuron2@attbi.com.
For updates and other filters/tools, visit my web site:
http://shelob.mordor.net/dgraft/